package com.yh.client;

import org.springframework.context.annotation.Configuration;
import org.springframework.integration.annotation.MessagingGateway;
import org.springframework.integration.mqtt.support.MqttHeaders;
import org.springframework.messaging.handler.annotation.Header;

/**
 * 消息发布网关接口，提供多个重载方法用于向 MQTT 服务器发送消息。
 * 使用 Spring Integration 的 MessagingGateway 注解实现，与出站通道（mqttOutboundChannel）集成，
 * 使得业务逻辑可以通过调用该接口的方法发送消息，而无需直接操作 MQTT 的具体实现。
 * <p>
 * 功能特点：
 * 1. 发送消息到默认 Topic。
 * 2. 发送消息到指定 Topic。
 * 3. 发送消息到指定 Topic，并支持设置 QoS 等级。
 * 4. 提供对字符串和字节数组类型的负载支持。
 */
@Configuration
@MessagingGateway(defaultRequestChannel = "mqttOutboundChannel")
public interface MqttGateway {

    /**
     * 发送消息到默认 Topic
     * <p>
     * 使用配置的默认 Topic 将字符串类型的负载发送到 MQTT 服务器。
     *
     * @param payload 消息负载，字符串类型
     */
    void sendToMqtt(String payload);

    /**
     * 发送消息到指定 Topic
     * <p>
     * 提供一个 Topic 参数，允许将消息发送到不同的 MQTT 话题，负载为字符串类型。
     *
     * @param topic   要发送到的 MQTT Topic
     * @param payload 消息负载，字符串类型
     */
    void sendToMqtt(@Header(MqttHeaders.TOPIC) String topic, String payload);

    /**
     * 发送消息到指定 Topic，并设置 QoS 等级
     * <p>
     * 提供 Topic 和 QoS 参数，允许设置消息发送的质量等级，负载为字符串类型。
     *
     * @param topic   要发送到的 MQTT Topic
     * @param qos     消息发送的 QoS 等级（0、1 或 2）
     * @param payload 消息负载，字符串类型
     */
    void sendToMqtt(@Header(MqttHeaders.TOPIC) String topic, @Header(MqttHeaders.QOS) int qos, String payload);

    /**
     * 发送消息到指定 Topic，并设置 QoS 等级（字节数组负载）
     * <p>
     * 提供 Topic 和 QoS 参数，允许设置消息发送的质量等级，负载为字节数组类型。
     *
     * @param topic   要发送到的 MQTT Topic
     * @param qos     消息发送的 QoS 等级（0、1 或 2）
     * @param payload 消息负载，字节数组类型
     */
    void sendToMqtt(@Header(MqttHeaders.TOPIC) String topic, @Header(MqttHeaders.QOS) int qos, byte[] payload);
}
